CodeAgent CLI 项目深挖 · 单期模块。总览见 需求分析 与 整体设计方案。

多模态解决的是「让 Agent 看得见图」——用户把截图、设计稿、报错截图粘进终端，模型基于图片内容回答，而不是只能处理文本。这一期同时覆盖了图片输入的完整链路：引用解析、剪贴板粘贴、预处理压缩、多模态消息组装与防幻觉提示。

图片从输入到模型消息的链路

1. 引用解析（ImageReferenceParser.userMessage）：扫描用户输入里的图片引用（路径 / image 标记）。没有引用 → 直接返回纯文本消息，零开销；
2. 加载：按引用从路径读取，或从系统剪贴板取图（ClipboardImage，截图后直接粘贴）；源图超 50MB 上限直接拒绝；
3. 预处理（ImageProcessor.process）：下采样到 2000×2000 以内，按 API 约束控制体积——base64 编码后不超过 5MB（对应原始字节 ≈3.75MB），超了先压缩再编码；
4. 组装多模态消息：文本部分 = 去掉图片引用后的输入 + 防御性指令 + 元数据注记，图片部分 = 图片附件，文本在前、图片在后，走 ContentPart 多段消息发给模型。

历史里的图片会不会撑爆上下文？

不会长期占。ReAct 每轮进入循环前都会执行 pruneHistoricalImagePayloads 清理历史图片载荷——当前轮的图片全量可见，历史轮只保留文本。多模态输入是「一次性观察」，不随轮次累积，这是多模态和上下文预算能共存的前提。

防御性提示词里那句「以当前图片为准」是防什么的？

防两类典型坑：一是模型不看图、凭历史对话或文件路径猜答案；二是模型调工具去重新读取图片文件，浪费一次调用。所以注入的指令明确要求：直接观察本轮图片附件；图片与历史上下文冲突时以图片为准；无法直接观察附件就明说，禁止用 MCP、文件系统或浏览器工具重读 Image source。

剪贴板粘贴是怎么实现的？

ClipboardImage 从系统剪贴板直接读取图片字节——用户截图后 Ctrl+V 粘贴，与路径引用走同一条 ImageProcessor 预处理管线。无效引用（文件不存在、超限、非图片）不会报错中断循环，而是转成「图片引用无效 + 原因」的注记文本给模型，让它自己决定怎么向用户解释。

对模型有什么要求？不支持视觉的模型怎么办？

要求 provider 支持视觉输入——图片到各家 message 格式的转换在多模型适配层的 toImageUrl hook 里完成（见 Prompt分层与模型接入）。如果模型不支持或看不了图，防御提示词明确要求它「说明无法看图」，而不是基于路径或历史上下文编一个答案。